<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Collections comparison</title>
<link rel="stylesheet" href="../../../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../../index.html" title="Boost.Test">
<link rel="up" href="../extended_comparison.html" title="Extended comparisons support">
<link rel="prev" href="strings.html" title="Strings and C-strings comparison">
<link rel="next" href="bitwise.html" title="Bitwise comparison">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="strings.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../extended_comparison.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="bitwise.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="boost_test.testing_tools.extended_comparison.collections"></a><a class="link" href="collections.html" title="Collections comparison">Collections
        comparison</a>
</h4></div></div></div>
<p>
          Instead of comparing a single value against another, there is often a need
          for comparing <span class="emphasis"><em>collections</em></span> of values. A collection
          and indirectly the values it contains may be considered in several ways:
        </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
              collection as a <span class="emphasis"><em>sequence of values</em></span>: this is the
              case for instance when <code class="computeroutput"><span class="identifier">N</span></code>
              values are stored in a container. Containers in this case are used
              for storing several values, and iterating over the containers yields
              sequences that can be compared <span class="bold"><strong>element-wise</strong></span>.
              The iteration should be in an order that is <span class="emphasis"><em>a priori</em></span>
              known <a href="#ftn.boost_test.testing_tools.extended_comparison.collections.f0" class="footnote" name="boost_test.testing_tools.extended_comparison.collections.f0"><sup class="footnote">[10]</sup></a>, for being able to compare the sequences. The values in
              the collection are independent each other, and subsets can be compared
              as well.
            </li>
<li class="listitem">
              collection as an <span class="emphasis"><em>ensemble</em></span>: this is the case where
              the elements of the collection define an <span class="emphasis"><em>entity</em></span>,
              and no element can be dissociated from the others. An example would
              be a collection of letters for a specific word in the natural language;
              in this settings any of the character in the word/collection depends
              <span class="emphasis"><em>semantically</em></span> on the other and it is not possible
              to take a subset of it without breaking the meaning of the word. Another
              example would be a vector of size <code class="computeroutput"><span class="identifier">N</span></code>
              representing a point in a <code class="computeroutput"><span class="identifier">N</span></code>
              dimensional space, compared to another point with the relation "<code class="computeroutput"><span class="special">&lt;</span></code>": the comparison is application
              specific and a possible comparison would be the lexicographical ordering
              <a href="#ftn.boost_test.testing_tools.extended_comparison.collections.f1" class="footnote" name="boost_test.testing_tools.extended_comparison.collections.f1"><sup class="footnote">[11]</sup></a>.
            </li>
</ul></div>
<p>
          The following observations can be done:
        </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
              the methods employed for comparing collections should be chosen adequately
              with the meaning of the collection,
            </li>
<li class="listitem">
              comparing sequences <span class="bold"><strong>element-wise</strong></span> often
              involves writing loops in the test body, and if a dedicated tool is
              already in place the test body would gain in clarity and expressiveness
              (including the report in case of failure),
            </li>
<li class="listitem">
              some comparison methods such as the lexicographical one, have good
              general behavior (e.g. total ordering, defined for collections of different
              size), but are sometimes inappropriate.
            </li>
</ul></div>
<p>
          <a class="link" href="../../utf_reference/testing_tool_ref/assertion_boost_test_universal_macro.html" title="BOOST_TEST"><code class="computeroutput"><span class="identifier">BOOST_TEST</span></code></a> provides specific tools
          for comparing collections:
        </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
              using the <span class="emphasis"><em>native</em></span> <a href="#ftn.boost_test.testing_tools.extended_comparison.collections.f2" class="footnote" name="boost_test.testing_tools.extended_comparison.collections.f2"><sup class="footnote">[12]</sup></a> operator of the container of the collection, which is mentioned
              as the <a class="link" href="collections.html#ref_boost_test_coll_default_comp"><span class="emphasis"><em>default
              behavior</em></span></a>.
            </li>
<li class="listitem">
              using <a class="link" href="collections.html#boost_test_coll_perelement">element-wise</a>
              comparison for which extended failure diagnostic is provided,
            </li>
<li class="listitem">
              and using <a class="link" href="collections.html#boost_test_coll_default_lex">lexicographical</a>
              comparison for which extended failure diagnostic is provided,
            </li>
</ul></div>
<p>
          More details about the concept of <span class="emphasis"><em>collection</em></span> in the
          <span class="emphasis"><em>Unit Test Framework</em></span> is given <a class="link" href="collections.html#what_is_a_collection"><span class="emphasis"><em>here</em></span></a>.
        </p>
<a name="ref_boost_test_coll_default_comp"></a><h4>
<a name="boost_test.testing_tools.extended_comparison.collections.h0"></a>
          <span class="phrase"><a name="boost_test.testing_tools.extended_comparison.collections.default_comparison"></a></span><a class="link" href="collections.html#boost_test.testing_tools.extended_comparison.collections.default_comparison">Default
          comparison</a>
        </h4>
<p>
          The default comparison dispatches to the existing overloaded comparison
          operator. The <span class="emphasis"><em>Unit Test Framework</em></span> distinguishes two
          use cases
        </p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">
              none of the comparison operand is a C-Array, in which case we use the
              <a class="link" href="collections.html#ref_boost_test_coll_default_comp_container">container
              default behavior</a>
            </li>
<li class="listitem">
              one of the comparison operand is a C-array, in which case we <a class="link" href="collections.html#ref_boost_test_coll_c_arrays">mimic <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code></a>
              behavior
            </li>
</ol></div>
<a name="ref_boost_test_coll_default_comp_container"></a><h5>
<a name="boost_test.testing_tools.extended_comparison.collections.h1"></a>
          <span class="phrase"><a name="boost_test.testing_tools.extended_comparison.collections.container_default_behavior"></a></span><a class="link" href="collections.html#boost_test.testing_tools.extended_comparison.collections.container_default_behavior">Container
          default behavior</a>
        </h5>
<p>
          Given two containers <code class="computeroutput"><span class="identifier">c_a</span></code>
          and <code class="computeroutput"><span class="identifier">c_b</span></code> that are not C-arrays,
        </p>
<pre class="programlisting"><span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">c_a</span> <span class="identifier">op</span> <span class="identifier">c_b</span><span class="special">)</span>
</pre>
<p>
          is equivalent, in terms of test success, to
        </p>
<pre class="programlisting"><span class="keyword">auto</span> <span class="identifier">result</span> <span class="special">=</span> <span class="identifier">c_a</span> <span class="identifier">op</span> <span class="identifier">c_b</span><span class="special">;</span>
<span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">result</span><span class="special">);</span>
</pre>
<p>
          In the example below, <code class="computeroutput"><span class="keyword">operator</span><span class="special">==</span></code> is not defined for <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code>
          of different types, and the program would fail to compile if the corresponding
          lines were uncommented (<code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code>
          uses lexicographical comparison by default).
        </p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
            In the case of default comparison, there is no additional diagnostic
            provided by the <span class="emphasis"><em>Unit Test Framework</em></span>. See the section
            <a class="link" href="collections.html#ref_boost_test_coll_special_macro"><code class="computeroutput"><span class="identifier">BOOST_TEST_SPECIALIZED_COLLECTION_COMPARE</span></code></a>
            below.
          </p></td></tr>
</table></div>
<h6>
<a name="boost_test.testing_tools.extended_comparison.collections.h2"></a>
          <span class="phrase"><a name="boost_test.testing_tools.extended_comparison.collections.example_descr"></a></span><a class="link" href="collections.html#boost_test.testing_tools.extended_comparison.collections.example_descr">Example:
          BOOST_TEST containers comparison default</a>
        </h6>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                  <p>
                    Code
                  </p>
                </th></tr></thead>
<tbody><tr><td>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_TEST_MODULE</span> <span class="identifier">boost_test_sequence</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">vector</span><span class="special">&gt;</span>

<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_collections_vectors</span> <span class="special">)</span>
<span class="special">{</span>
  <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">a</span><span class="special">{</span><span class="number">1</span><span class="special">,</span><span class="number">2</span><span class="special">,</span><span class="number">3</span><span class="special">},</span> <span class="identifier">c</span><span class="special">{</span><span class="number">1</span><span class="special">,</span><span class="number">5</span><span class="special">,</span><span class="number">3</span><span class="special">,</span><span class="number">4</span><span class="special">};</span>
  <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">long</span><span class="special">&gt;</span> <span class="identifier">b</span><span class="special">{</span><span class="number">1</span><span class="special">,</span><span class="number">5</span><span class="special">,</span><span class="number">3</span><span class="special">};</span>

  <span class="comment">// the following does not compile</span>
  <span class="comment">//BOOST_TEST(a == b);</span>
  <span class="comment">//BOOST_TEST(a &lt;= b);</span>

  <span class="comment">// stl defaults to lexicographical comparison</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">c</span><span class="special">);</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">&gt;=</span> <span class="identifier">c</span><span class="special">);</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">!=</span> <span class="identifier">c</span><span class="special">);</span>
<span class="special">}</span>
</pre>
                </td></tr></tbody>
</table></div>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                  <p>
                    Output
                  </p>
                </th></tr></thead>
<tbody><tr><td>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span> <span class="special">./</span><span class="identifier">boost_test_container_default</span> <span class="special">--</span><span class="identifier">log_level</span><span class="special">=</span><span class="identifier">all</span>
<span class="identifier">Running</span> <span class="number">1</span> <span class="identifier">test</span> <span class="keyword">case</span><span class="special">...</span>
<span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"boost_test_sequence"</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">13</span><span class="special">):</span> <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_collections_vectors"</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">23</span><span class="special">):</span> <span class="identifier">info</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">c</span> <span class="identifier">has</span> <span class="identifier">passed</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">24</span><span class="special">):</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_collections_vectors"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">&gt;=</span> <span class="identifier">c</span> <span class="identifier">has</span> <span class="identifier">failed</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">25</span><span class="special">):</span> <span class="identifier">info</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">!=</span> <span class="identifier">c</span> <span class="identifier">has</span> <span class="identifier">passed</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">(</span><span class="number">13</span><span class="special">):</span> <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_collections_vectors"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">208u</span><span class="identifier">s</span>
<span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"boost_test_sequence"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">286u</span><span class="identifier">s</span>

<span class="special">***</span> <span class="number">1</span> <span class="identifier">failure</span> <span class="identifier">is</span> <span class="identifier">detected</span> <span class="identifier">in</span> <span class="identifier">the</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"boost_test_container_default"</span>
</pre>
                </td></tr></tbody>
</table></div>
<a name="ref_boost_test_coll_c_arrays"></a><h5>
<a name="boost_test.testing_tools.extended_comparison.collections.h3"></a>
          <span class="phrase"><a name="boost_test.testing_tools.extended_comparison.collections.c_arrays_default_behavior"></a></span><a class="link" href="collections.html#boost_test.testing_tools.extended_comparison.collections.c_arrays_default_behavior">C-arrays
          default behavior</a>
        </h5>
<p>
          As soon as one of the operands is a C-array, there is no <span class="emphasis"><em>default
          behavior</em></span> the <span class="emphasis"><em>Unit Test Framework</em></span> can dispatch
          to. This is why in that case, the comparison mimics the <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span></code>
          behavior.
        </p>
<h6>
<a name="boost_test.testing_tools.extended_comparison.collections.h4"></a>
          <span class="phrase"><a name="boost_test.testing_tools.extended_comparison.collections.example_descr0"></a></span><a class="link" href="collections.html#boost_test.testing_tools.extended_comparison.collections.example_descr0">Example:
          BOOST_TEST C-arrays</a>
        </h6>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                  <p>
                    Code
                  </p>
                </th></tr></thead>
<tbody><tr><td>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_TEST_MODULE</span> <span class="identifier">boost_test_containers_c_arrays</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">vector</span><span class="special">&gt;</span>

<span class="keyword">namespace</span> <span class="identifier">tt</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">;</span>

<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_collections_on_c_arrays</span> <span class="special">)</span>
<span class="special">{</span>
  <span class="keyword">int</span> <span class="identifier">a</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span><span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">,</span> <span class="number">3</span><span class="special">};</span>
  <span class="keyword">int</span> <span class="identifier">b</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span><span class="number">1</span><span class="special">,</span> <span class="number">5</span><span class="special">,</span> <span class="number">3</span><span class="special">,</span> <span class="number">4</span><span class="special">};</span>
  <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">long</span><span class="special">&gt;</span> <span class="identifier">c</span><span class="special">{</span><span class="number">1</span><span class="special">,</span> <span class="number">5</span><span class="special">,</span> <span class="number">3</span><span class="special">,</span> <span class="number">4</span><span class="special">};</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">==</span> <span class="identifier">a</span><span class="special">);</span> <span class="comment">// element-wise compare</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">==</span> <span class="identifier">b</span><span class="special">);</span> <span class="comment">// element-wise compare</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">!=</span> <span class="identifier">b</span><span class="special">);</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">b</span><span class="special">);</span> <span class="comment">// lexicographical compare</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">b</span> <span class="special">&lt;</span> <span class="identifier">c</span><span class="special">);</span> <span class="comment">// lexicographical compare</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">c</span> <span class="special">&lt;</span> <span class="identifier">a</span><span class="special">);</span> <span class="comment">// lexicographical compare</span>
<span class="special">}</span>
</pre>
                </td></tr></tbody>
</table></div>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                  <p>
                    Output
                  </p>
                </th></tr></thead>
<tbody><tr><td>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span> <span class="special">./</span><span class="identifier">boost_test_containers_c_arrays</span> <span class="special">--</span><span class="identifier">log_level</span><span class="special">=</span><span class="identifier">all</span>
<span class="identifier">Running</span> <span class="number">1</span> <span class="identifier">test</span> <span class="keyword">case</span><span class="special">...</span>
<span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"boost_test_containers_c_arrays"</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">15</span><span class="special">:</span> <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_collections_on_c_arrays"</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">20</span><span class="special">:</span> <span class="identifier">info</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">==</span> <span class="identifier">a</span> <span class="identifier">has</span> <span class="identifier">passed</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">21</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_collections_on_c_arrays"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">==</span> <span class="identifier">b</span> <span class="identifier">has</span> <span class="identifier">failed</span><span class="special">.</span>
<span class="identifier">Collections</span> <span class="identifier">size</span> <span class="identifier">mismatch</span><span class="special">:</span> <span class="number">3</span> <span class="special">!=</span> <span class="number">4</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">22</span><span class="special">:</span> <span class="identifier">info</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">!=</span> <span class="identifier">b</span> <span class="identifier">has</span> <span class="identifier">passed</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">23</span><span class="special">:</span> <span class="identifier">info</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">b</span> <span class="identifier">has</span> <span class="identifier">passed</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">24</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_collections_on_c_arrays"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">b</span> <span class="special">&lt;</span> <span class="identifier">c</span> <span class="identifier">has</span> <span class="identifier">failed</span><span class="special">.</span>
<span class="identifier">Collections</span> <span class="identifier">appear</span> <span class="identifier">to</span> <span class="identifier">be</span> <span class="identifier">equal</span><span class="special">.</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">25</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_collections_on_c_arrays"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">c</span> <span class="special">&lt;</span> <span class="identifier">a</span> <span class="identifier">has</span> <span class="identifier">failed</span><span class="special">.</span>
<span class="identifier">Failure</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">1</span><span class="special">:</span> <span class="number">5</span> <span class="special">&gt;=</span> <span class="number">2.</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">15</span><span class="special">:</span> <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_collections_on_c_arrays"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">204u</span><span class="identifier">s</span>
<span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"boost_test_containers_c_arrays"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">240u</span><span class="identifier">s</span>

<span class="special">***</span> <span class="number">3</span> <span class="identifier">failures</span> <span class="identifier">are</span> <span class="identifier">detected</span> <span class="identifier">in</span> <span class="identifier">the</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"boost_test_containers_c_arrays"</span>
</pre>
                </td></tr></tbody>
</table></div>
<a name="boost_test_coll_perelement"></a><h4>
<a name="boost_test.testing_tools.extended_comparison.collections.h5"></a>
          <span class="phrase"><a name="boost_test.testing_tools.extended_comparison.collections.element_wise_comparison"></a></span><a class="link" href="collections.html#boost_test.testing_tools.extended_comparison.collections.element_wise_comparison">Element-wise
          comparison</a>
        </h4>
<p>
          By specifying the manipulator <code class="computeroutput"><a class="link" href="../../../boost/test_tools/per_element.html" title="Struct per_element">boost::test_tools::per_element</a></code>,
          the comparison of the elements of the containers are performed <span class="emphasis"><em>element-wise</em></span>,
          in the order given by the forward iterators of the containers. This is
          a comparison on the <span class="emphasis"><em>sequences</em></span> of elements generated
          by the containers, for which the <span class="emphasis"><em>Unit Test Framework</em></span>
          provides advanced diagnostic.
        </p>
<p>
          In more details, let <code class="computeroutput"><span class="identifier">c_a</span> <span class="special">=</span> <span class="special">(</span><span class="identifier">a_1</span><span class="special">,...</span> <span class="identifier">a_n</span><span class="special">)</span></code> and <code class="computeroutput"><span class="identifier">c_b</span>
          <span class="special">=</span> <span class="special">(</span><span class="identifier">b_1</span><span class="special">,...</span> <span class="identifier">b_n</span><span class="special">)</span></code>
          be two sequences of same length, but not necessarily of same type. Those
          sequences correspond to the content of the respective containers, in the
          order given by their iterator. Let <code class="computeroutput"><span class="identifier">op</span></code>
          be one of the <a class="link" href="../boost_test_universal_macro.html#boost_test_statement_overloads">binary comparison
          operators</a>.
        </p>
<pre class="programlisting"><span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">c_a</span> <span class="identifier">op</span> <span class="identifier">c_b</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">per_element</span><span class="special">()</span> <span class="special">);</span>
</pre>
<p>
          is equivalent to
        </p>
<pre class="programlisting"><span class="keyword">if</span><span class="special">(</span><span class="identifier">c_a</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span> <span class="special">==</span> <span class="identifier">c_b</span><span class="special">.</span><span class="identifier">size</span><span class="special">())</span>
<span class="special">{</span>
  <span class="keyword">for</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span><span class="special">=</span><span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;</span> <span class="identifier">c_a</span><span class="special">.</span><span class="identifier">size</span><span class="special">();</span> <span class="identifier">i</span><span class="special">++)</span>
  <span class="special">{</span>
    <a class="link" href="../../utf_reference/testout_reference/test_output_macro_context.html" title="BOOST_TEST_CONTEXT"><code class="computeroutput"><span class="identifier">BOOST_TEST_CONTEXT</span></code></a><span class="special">(</span><span class="string">"index "</span> <span class="special">&lt;&lt;</span> <span class="identifier">i</span><span class="special">)</span>
    <span class="special">{</span>
      <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a_i</span> <span class="identifier">op</span> <span class="identifier">b_i</span><span class="special">);</span>
    <span class="special">}</span>
  <span class="special">}</span>
<span class="special">}</span>
<span class="keyword">else</span>
<span class="special">{</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">c_a</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span> <span class="special">==</span> <span class="identifier">c_b</span><span class="special">.</span><span class="identifier">size</span><span class="special">());</span>
<span class="special">}</span>
</pre>
<div class="warning"><table border="0" summary="Warning">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../../../doc/src/images/warning.png"></td>
<th align="left">Warning</th>
</tr>
<tr><td align="left" valign="top"><p>
            this is fundamentally different from using the containers' default comparison
            operators (default behavior).
          </p></td></tr>
</table></div>
<div class="warning"><table border="0" summary="Warning">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../../../doc/src/images/warning.png"></td>
<th align="left">Warning</th>
</tr>
<tr><td align="left" valign="top">
<p>
            this is not an order relationship on containers. As a side effect, it
            is possible to have
          </p>
<pre class="programlisting"><span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">c_a</span> <span class="special">==</span> <span class="identifier">c_b</span><span class="special">)</span></pre>
<p>
            and
          </p>
<pre class="programlisting"><span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">c_a</span> <span class="special">!=</span> <span class="identifier">c_b</span><span class="special">)</span></pre>
<p>
            failing at the same time
          </p>
</td></tr>
</table></div>
<p>
          Sequences are compared using the specified operator <code class="computeroutput"><span class="identifier">op</span></code>,
          evaluated on the left and right elements of the respective sequences. The
          order of the compared elements is given by the iterators of the respective
          containers <a href="#ftn.boost_test.testing_tools.extended_comparison.collections.f3" class="footnote" name="boost_test.testing_tools.extended_comparison.collections.f3"><sup class="footnote">[13]</sup></a>. In case of failure, the indices of the elements failing <code class="computeroutput"><span class="identifier">op</span></code> are returned.
        </p>
<h6>
<a name="boost_test.testing_tools.extended_comparison.collections.h6"></a>
          <span class="phrase"><a name="boost_test.testing_tools.extended_comparison.collections.example_descr1"></a></span><a class="link" href="collections.html#boost_test.testing_tools.extended_comparison.collections.example_descr1">Example:
          BOOST_TEST sequence comparison</a>
        </h6>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                  <p>
                    Code
                  </p>
                </th></tr></thead>
<tbody><tr><td>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_TEST_MODULE</span> <span class="identifier">boost_test_sequence_per_element</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">vector</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">list</span><span class="special">&gt;</span>
<span class="keyword">namespace</span> <span class="identifier">tt</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">;</span>

<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_sequence_per_element</span> <span class="special">)</span>
<span class="special">{</span>
  <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">a</span><span class="special">{</span><span class="number">1</span><span class="special">,</span><span class="number">2</span><span class="special">,</span><span class="number">3</span><span class="special">};</span>
  <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">long</span><span class="special">&gt;</span> <span class="identifier">b</span><span class="special">{</span><span class="number">1</span><span class="special">,</span><span class="number">5</span><span class="special">,</span><span class="number">3</span><span class="special">};</span>
  <span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span><span class="special">&lt;</span><span class="keyword">short</span><span class="special">&gt;</span> <span class="identifier">c</span><span class="special">{</span><span class="number">1</span><span class="special">,</span><span class="number">5</span><span class="special">,</span><span class="number">3</span><span class="special">,</span><span class="number">4</span><span class="special">};</span>

  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">==</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">tt</span><span class="special">::</span><span class="identifier">per_element</span><span class="special">());</span> <span class="comment">// nok: a[1] != b[1]</span>

  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">!=</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">tt</span><span class="special">::</span><span class="identifier">per_element</span><span class="special">());</span> <span class="comment">// nok: a[0] == b[0] ...</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">&lt;=</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">tt</span><span class="special">::</span><span class="identifier">per_element</span><span class="special">());</span> <span class="comment">// ok</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">b</span>  <span class="special">&lt;</span> <span class="identifier">c</span><span class="special">,</span> <span class="identifier">tt</span><span class="special">::</span><span class="identifier">per_element</span><span class="special">());</span> <span class="comment">// nok: size mismatch</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">b</span> <span class="special">&gt;=</span> <span class="identifier">c</span><span class="special">,</span> <span class="identifier">tt</span><span class="special">::</span><span class="identifier">per_element</span><span class="special">());</span> <span class="comment">// nok: size mismatch</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">b</span> <span class="special">!=</span> <span class="identifier">c</span><span class="special">,</span> <span class="identifier">tt</span><span class="special">::</span><span class="identifier">per_element</span><span class="special">());</span> <span class="comment">// nok: size mismatch</span>
<span class="special">}</span>

<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_compare_c_arrays_element_wise</span> <span class="special">)</span>
<span class="special">{</span>
  <span class="keyword">int</span> <span class="identifier">a</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span><span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">,</span> <span class="number">3</span><span class="special">};</span>
  <span class="keyword">int</span> <span class="identifier">b</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span><span class="number">1</span><span class="special">,</span> <span class="number">5</span><span class="special">,</span> <span class="number">3</span><span class="special">};</span>
  <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">long</span><span class="special">&gt;</span> <span class="identifier">c</span><span class="special">{</span><span class="number">1</span><span class="special">,</span> <span class="number">5</span><span class="special">,</span> <span class="number">3</span><span class="special">};</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">==</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">per_element</span><span class="special">());</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">!=</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">per_element</span><span class="special">());</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">per_element</span><span class="special">());</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">b</span> <span class="special">&lt;</span> <span class="identifier">c</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">per_element</span><span class="special">());</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">c</span> <span class="special">&lt;</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">per_element</span><span class="special">());</span>
<span class="special">}</span>
</pre>
                </td></tr></tbody>
</table></div>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                  <p>
                    Output
                  </p>
                </th></tr></thead>
<tbody><tr><td>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span> <span class="special">./</span><span class="identifier">boost_test_sequence_per_element</span>
<span class="identifier">Running</span> <span class="number">2</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">21</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_sequence_per_element"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">==</span> <span class="identifier">b</span> <span class="identifier">has</span> <span class="identifier">failed</span>
<span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">1</span><span class="special">:</span> <span class="number">2</span> <span class="special">!=</span> <span class="number">5.</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">23</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_sequence_per_element"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">!=</span> <span class="identifier">b</span> <span class="identifier">has</span> <span class="identifier">failed</span>
<span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">0</span><span class="special">:</span> <span class="number">1</span> <span class="special">==</span> <span class="number">1.</span>
<span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">2</span><span class="special">:</span> <span class="number">3</span> <span class="special">==</span> <span class="number">3.</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">25</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_sequence_per_element"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">b</span> <span class="special">&lt;</span> <span class="identifier">c</span> <span class="identifier">has</span> <span class="identifier">failed</span>
<span class="identifier">Collections</span> <span class="identifier">size</span> <span class="identifier">mismatch</span><span class="special">:</span> <span class="number">3</span> <span class="special">!=</span> <span class="number">4</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">26</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_sequence_per_element"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">b</span> <span class="special">&gt;=</span> <span class="identifier">c</span> <span class="identifier">has</span> <span class="identifier">failed</span>
<span class="identifier">Collections</span> <span class="identifier">size</span> <span class="identifier">mismatch</span><span class="special">:</span> <span class="number">3</span> <span class="special">!=</span> <span class="number">4</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">27</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_sequence_per_element"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">b</span> <span class="special">!=</span> <span class="identifier">c</span> <span class="identifier">has</span> <span class="identifier">failed</span>
<span class="identifier">Collections</span> <span class="identifier">size</span> <span class="identifier">mismatch</span><span class="special">:</span> <span class="number">3</span> <span class="special">!=</span> <span class="number">4</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">35</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_compare_c_arrays_element_wise"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">==</span> <span class="identifier">b</span> <span class="identifier">has</span> <span class="identifier">failed</span>
<span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">1</span><span class="special">:</span> <span class="number">2</span> <span class="special">!=</span> <span class="number">5.</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">36</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_compare_c_arrays_element_wise"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">!=</span> <span class="identifier">b</span> <span class="identifier">has</span> <span class="identifier">failed</span>
<span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">0</span><span class="special">:</span> <span class="number">1</span> <span class="special">==</span> <span class="number">1.</span>
<span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">2</span><span class="special">:</span> <span class="number">3</span> <span class="special">==</span> <span class="number">3.</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">37</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_compare_c_arrays_element_wise"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">b</span> <span class="identifier">has</span> <span class="identifier">failed</span>
<span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">0</span><span class="special">:</span> <span class="number">1</span> <span class="special">&gt;=</span> <span class="number">1.</span>
<span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">2</span><span class="special">:</span> <span class="number">3</span> <span class="special">&gt;=</span> <span class="number">3.</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">38</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_compare_c_arrays_element_wise"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">b</span> <span class="special">&lt;</span> <span class="identifier">c</span> <span class="identifier">has</span> <span class="identifier">failed</span>
<span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">0</span><span class="special">:</span> <span class="number">1</span> <span class="special">&gt;=</span> <span class="number">1.</span>
<span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">1</span><span class="special">:</span> <span class="number">5</span> <span class="special">&gt;=</span> <span class="number">5.</span>
<span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">2</span><span class="special">:</span> <span class="number">3</span> <span class="special">&gt;=</span> <span class="number">3.</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">39</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_compare_c_arrays_element_wise"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">c</span> <span class="special">&lt;</span> <span class="identifier">a</span> <span class="identifier">has</span> <span class="identifier">failed</span>
<span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">0</span><span class="special">:</span> <span class="number">1</span> <span class="special">&gt;=</span> <span class="number">1.</span>
<span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">1</span><span class="special">:</span> <span class="number">5</span> <span class="special">&gt;=</span> <span class="number">2.</span>
<span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">2</span><span class="special">:</span> <span class="number">3</span> <span class="special">&gt;=</span> <span class="number">3.</span>

<span class="special">***</span> <span class="number">10</span> <span class="identifier">failures</span> <span class="identifier">are</span> <span class="identifier">detected</span> <span class="identifier">in</span> <span class="identifier">the</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"boost_test_sequence_per_element"</span>
</pre>
                </td></tr></tbody>
</table></div>
<h5>
<a name="boost_test.testing_tools.extended_comparison.collections.h7"></a>
          <span class="phrase"><a name="boost_test.testing_tools.extended_comparison.collections.requirements"></a></span><a class="link" href="collections.html#boost_test.testing_tools.extended_comparison.collections.requirements">Requirements</a>
        </h5>
<p>
          For the sequences to be comparable element-wise, the following conditions
          should be met:
        </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
              the containers should meet the <a class="link" href="collections.html#what_is_a_collection">sequence</a>
              definition,
            </li>
<li class="listitem">
              the containers should yield the same number of elements,
            </li>
<li class="listitem">
              <code class="computeroutput"><span class="identifier">op</span></code> should be one of
              the comparison operator <code class="computeroutput"><span class="special">==</span></code>,
              <code class="computeroutput"><span class="special">!=</span></code>, <code class="computeroutput"><span class="special">&lt;</span></code>,
              <code class="computeroutput"><span class="special">&lt;=</span></code>, <code class="computeroutput"><span class="special">&gt;</span></code>,
              <code class="computeroutput"><span class="special">&gt;=</span></code>
            </li>
<li class="listitem">
              the <code class="computeroutput"><span class="identifier">a_i</span> <span class="identifier">op</span>
              <span class="identifier">b_i</span></code> should be defined, where
              the type of <code class="computeroutput"><span class="identifier">a_i</span></code> and
              <code class="computeroutput"><span class="identifier">b_i</span></code> are the type returned
              by the dereference operator of the respective collections.
            </li>
</ul></div>
<div class="caution"><table border="0" summary="Caution">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../doc/src/images/caution.png"></td>
<th align="left">Caution</th>
</tr>
<tr><td align="left" valign="top">
<p>
            the resulting type of "<code class="computeroutput"><span class="identifier">c_a</span>
            <span class="special">==</span> <span class="identifier">c_b</span></code>"
            is an <code class="computeroutput"><a class="link" href="../../../boost/test_tools/assertion_result.html" title="Class assertion_result">assertion_result</a></code>:
            it is not possible to compose more that one comparison on the <code class="computeroutput"><span class="identifier">BOOST_TEST</span></code> statement:
          </p>
<pre class="programlisting"><span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">c_a</span> <span class="special">==</span> <span class="identifier">c_b</span> <span class="special">==</span> <span class="number">42</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">per_element</span><span class="special">()</span> <span class="special">);</span> <span class="comment">// does not compile</span>
</pre>
</td></tr>
</table></div>
<a name="boost_test_coll_default_lex"></a><h4>
<a name="boost_test.testing_tools.extended_comparison.collections.h8"></a>
          <span class="phrase"><a name="boost_test.testing_tools.extended_comparison.collections.lexicographic_comparison"></a></span><a class="link" href="collections.html#boost_test.testing_tools.extended_comparison.collections.lexicographic_comparison">Lexicographic
          comparison</a>
        </h4>
<p>
          By specifying the manipulator <code class="computeroutput"><a class="link" href="../../../boost/test_tools/lexicographic.html" title="Struct lexicographic">boost::test_tools::lexicographic</a></code>,
          the containers are compared using the <span class="emphasis"><em>lexicographical</em></span>
          order and for which the <span class="emphasis"><em>Unit Test Framework</em></span> provides
          additional diagnostic in case of failure.
        </p>
<pre class="programlisting"><span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">c_a</span> <span class="identifier">op</span> <span class="identifier">c_b</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">lexicographic</span><span class="special">()</span> <span class="special">);</span>
</pre>
<p>
          The comparison is performed in the order given by forward iterators of
          the containers.
        </p>
<div class="tip"><table border="0" summary="Tip">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../../doc/src/images/tip.png"></td>
<th align="left">Tip</th>
</tr>
<tr><td align="left" valign="top"><p>
            lexicographic comparison yields a total order on the containers: the
            statements <code class="computeroutput"><span class="identifier">c_a</span> <span class="special">&lt;</span>
            <span class="identifier">c_b</span></code> and <code class="computeroutput"><span class="identifier">c_b</span>
            <span class="special">&lt;=</span> <span class="identifier">c_a</span></code>
            are mutually exclusive.
          </p></td></tr>
</table></div>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
            The equality <code class="computeroutput"><span class="special">==</span></code> and inequality
            <code class="computeroutput"><span class="special">!=</span></code> are not available for
            this type of comparison.
          </p></td></tr>
</table></div>
<h6>
<a name="boost_test.testing_tools.extended_comparison.collections.h9"></a>
          <span class="phrase"><a name="boost_test.testing_tools.extended_comparison.collections.example_descr2"></a></span><a class="link" href="collections.html#boost_test.testing_tools.extended_comparison.collections.example_descr2">Example:
          BOOST_TEST container comparison using lexicographical order</a>
        </h6>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                  <p>
                    Code
                  </p>
                </th></tr></thead>
<tbody><tr><td>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_TEST_MODULE</span> <span class="identifier">boost_test_container_lex</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">vector</span><span class="special">&gt;</span>

<span class="keyword">namespace</span> <span class="identifier">tt</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">;</span>

<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_collections_vectors_lex</span> <span class="special">)</span>
<span class="special">{</span>
  <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">a</span><span class="special">{</span><span class="number">1</span><span class="special">,</span><span class="number">2</span><span class="special">,</span><span class="number">3</span><span class="special">},</span> <span class="identifier">b</span><span class="special">{</span><span class="number">1</span><span class="special">,</span><span class="number">2</span><span class="special">,</span><span class="number">2</span><span class="special">},</span> <span class="identifier">c</span><span class="special">{</span><span class="number">1</span><span class="special">,</span><span class="number">2</span><span class="special">,</span><span class="number">3</span><span class="special">,</span><span class="number">4</span><span class="special">};</span>

  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">tt</span><span class="special">::</span><span class="identifier">lexicographic</span><span class="special">());</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">tt</span><span class="special">::</span><span class="identifier">lexicographic</span><span class="special">());</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">c</span><span class="special">,</span> <span class="identifier">tt</span><span class="special">::</span><span class="identifier">lexicographic</span><span class="special">());</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">&gt;=</span> <span class="identifier">c</span><span class="special">,</span> <span class="identifier">tt</span><span class="special">::</span><span class="identifier">lexicographic</span><span class="special">());</span>

  <span class="comment">//BOOST_TEST(a == c, tt::lexicographic()); // does not compile</span>
  <span class="comment">//BOOST_TEST(a != c, tt::lexicographic()); // does not compile</span>
<span class="special">}</span>

<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_compare_c_arrays_lexicographic</span> <span class="special">)</span>
<span class="special">{</span>
  <span class="keyword">int</span> <span class="identifier">a</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span><span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">,</span> <span class="number">3</span><span class="special">};</span>
  <span class="keyword">int</span> <span class="identifier">b</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span><span class="number">1</span><span class="special">,</span> <span class="number">5</span><span class="special">,</span> <span class="number">3</span><span class="special">};</span>
  <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">long</span><span class="special">&gt;</span> <span class="identifier">c</span><span class="special">{</span><span class="number">1</span><span class="special">,</span> <span class="number">5</span><span class="special">,</span> <span class="number">3</span><span class="special">};</span>
  <span class="comment">// BOOST_TEST(a == b, boost::test_tools::lexicographic()); // does not compile</span>
  <span class="comment">// BOOST_TEST(a != b, boost::test_tools::lexicographic()); // does not compile</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">b</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">lexicographic</span><span class="special">());</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">b</span> <span class="special">&lt;</span> <span class="identifier">c</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">lexicographic</span><span class="special">());</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">c</span> <span class="special">&lt;</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">lexicographic</span><span class="special">());</span>
<span class="special">}</span>
</pre>
                </td></tr></tbody>
</table></div>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                  <p>
                    Output
                  </p>
                </th></tr></thead>
<tbody><tr><td>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span> <span class="special">./</span><span class="identifier">boost_test_container_lex</span> <span class="special">--</span><span class="identifier">log_level</span><span class="special">=</span><span class="identifier">all</span>
<span class="identifier">Running</span> <span class="number">2</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span>
<span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"boost_test_container_lex"</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">15</span><span class="special">:</span> <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_collections_vectors_lex"</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">19</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_collections_vectors_lex"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">a</span> <span class="identifier">has</span> <span class="identifier">failed</span>
<span class="identifier">Collections</span> <span class="identifier">appear</span> <span class="identifier">to</span> <span class="identifier">be</span> <span class="identifier">equal</span><span class="special">.</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">20</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_collections_vectors_lex"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">b</span> <span class="identifier">has</span> <span class="identifier">failed</span>
<span class="identifier">Failure</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">2</span><span class="special">:</span> <span class="number">3</span> <span class="special">&gt;=</span> <span class="number">2.</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">21</span><span class="special">:</span> <span class="identifier">info</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">c</span> <span class="identifier">has</span> <span class="identifier">passed</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">22</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_collections_vectors_lex"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">&gt;=</span> <span class="identifier">c</span> <span class="identifier">has</span> <span class="identifier">failed</span>
<span class="identifier">Second</span> <span class="identifier">collection</span> <span class="identifier">has</span> <span class="identifier">extra</span> <span class="identifier">trailing</span> <span class="identifier">elements</span><span class="special">.</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">15</span><span class="special">:</span> <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_collections_vectors_lex"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">178u</span><span class="identifier">s</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">28</span><span class="special">:</span> <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_compare_c_arrays_lexicographic"</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">35</span><span class="special">:</span> <span class="identifier">info</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">b</span> <span class="identifier">has</span> <span class="identifier">passed</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">36</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_compare_c_arrays_lexicographic"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">b</span> <span class="special">&lt;</span> <span class="identifier">c</span> <span class="identifier">has</span> <span class="identifier">failed</span>
<span class="identifier">Collections</span> <span class="identifier">appear</span> <span class="identifier">to</span> <span class="identifier">be</span> <span class="identifier">equal</span><span class="special">.</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">37</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_compare_c_arrays_lexicographic"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">c</span> <span class="special">&lt;</span> <span class="identifier">a</span> <span class="identifier">has</span> <span class="identifier">failed</span>
<span class="identifier">Failure</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">1</span><span class="special">:</span> <span class="number">5</span> <span class="special">&gt;=</span> <span class="number">2.</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">28</span><span class="special">:</span> <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_compare_c_arrays_lexicographic"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">88u</span><span class="identifier">s</span>
<span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"boost_test_container_lex"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">323u</span><span class="identifier">s</span>

<span class="special">***</span> <span class="number">5</span> <span class="identifier">failures</span> <span class="identifier">are</span> <span class="identifier">detected</span> <span class="identifier">in</span> <span class="identifier">the</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"boost_test_container_lex"</span>
</pre>
                </td></tr></tbody>
</table></div>
<a name="ref_boost_test_coll_special_macro"></a><h4>
<a name="boost_test.testing_tools.extended_comparison.collections.h10"></a>
          <span class="phrase"><a name="boost_test.testing_tools.extended_comparison.collections.extended_diagnostic_by_default_f"></a></span><a class="link" href="collections.html#boost_test.testing_tools.extended_comparison.collections.extended_diagnostic_by_default_f">Extended
          diagnostic by default for specific containers</a>
        </h4>
<p>
          As seen above,
        </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
              for testing equality, the <code class="computeroutput"><span class="special">==</span></code>
              relation is either explicit (using <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">per_element</span><span class="special">()</span></code>) or implicit when the container overloads/implements
              this type of comparison,
            </li>
<li class="listitem">
              for testing inequality, lexicographical comparison for <code class="computeroutput"><span class="special">&lt;</span></code> (and derived operations) is either
              explicit (using <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">::</span><span class="identifier">lexicographic</span><span class="special">()</span></code>) or implicit when the container overloads/implements
              uses this type of comparison.
            </li>
</ul></div>
<p>
          When the default is to using the container implementation, it is not possible
          to benefit from an extended failure diagnostic. The <span class="emphasis"><em>Unit Test
          Framework</em></span> provides a mechanism for performing the same comparisons
          through the <span class="emphasis"><em>Unit Test Framework</em></span> instead of the container
          operator, through the macro <code class="computeroutput"><span class="identifier">BOOST_TEST_SPECIALIZED_COLLECTION_COMPARE</span></code>
          that might be used as follow:
        </p>
<h6>
<a name="boost_test.testing_tools.extended_comparison.collections.h11"></a>
          <span class="phrase"><a name="boost_test.testing_tools.extended_comparison.collections.example_descr3"></a></span><a class="link" href="collections.html#boost_test.testing_tools.extended_comparison.collections.example_descr3">Example:
          Default <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span></code>
          to lexicographic with extended diagnostic</a>
        </h6>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                  <p>
                    Code
                  </p>
                </th></tr></thead>
<tbody><tr><td>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_TEST_MODULE</span> <span class="identifier">boost_test_container_lex_default</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">vector</span><span class="special">&gt;</span>

<span class="keyword">namespace</span> <span class="identifier">tt</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">test_tools</span><span class="special">;</span>

<span class="identifier">BOOST_TEST_SPECIALIZED_COLLECTION_COMPARE</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;)</span>

<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span> <span class="identifier">test_collections_vectors_lex</span> <span class="special">)</span>
<span class="special">{</span>
  <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">a</span><span class="special">{</span><span class="number">1</span><span class="special">,</span><span class="number">2</span><span class="special">,</span><span class="number">3</span><span class="special">},</span> <span class="identifier">b</span><span class="special">{</span><span class="number">1</span><span class="special">,</span><span class="number">2</span><span class="special">,</span><span class="number">2</span><span class="special">};</span>
  <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">long</span> <span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">c</span><span class="special">{</span><span class="number">1</span><span class="special">,</span><span class="number">2</span><span class="special">,</span><span class="number">3</span><span class="special">,</span><span class="number">5</span><span class="special">},</span> <span class="identifier">d</span><span class="special">{</span><span class="number">1</span><span class="special">,</span><span class="number">2</span><span class="special">,</span><span class="number">3</span><span class="special">,</span><span class="number">4</span><span class="special">};</span>

  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">a</span><span class="special">);</span> <span class="comment">// lexcographic</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">b</span><span class="special">);</span> <span class="comment">// lexcographic</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">==</span> <span class="identifier">b</span><span class="special">);</span> <span class="comment">// element-wise</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">a</span> <span class="special">!=</span> <span class="identifier">b</span><span class="special">);</span> <span class="comment">// extended diagnostic</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">c</span> <span class="special">&lt;</span> <span class="identifier">d</span><span class="special">);</span> <span class="comment">// no extended diagnostic</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="identifier">c</span> <span class="special">==</span> <span class="identifier">d</span><span class="special">);</span> <span class="comment">// no extended diagnostic</span>
<span class="special">}</span>
</pre>
                </td></tr></tbody>
</table></div>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                  <p>
                    Output
                  </p>
                </th></tr></thead>
<tbody><tr><td>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span> <span class="special">./</span><span class="identifier">boost_test_container_lex_default</span> <span class="special">--</span><span class="identifier">log_level</span><span class="special">=</span><span class="identifier">all</span>
<span class="identifier">Running</span> <span class="number">1</span> <span class="identifier">test</span> <span class="keyword">case</span><span class="special">...</span>
<span class="identifier">Entering</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"boost_test_container_lex_default"</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">17</span><span class="special">:</span> <span class="identifier">Entering</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_collections_vectors_lex"</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">22</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_collections_vectors_lex"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">a</span> <span class="identifier">has</span> <span class="identifier">failed</span><span class="special">.</span>
<span class="identifier">Collections</span> <span class="identifier">appear</span> <span class="identifier">to</span> <span class="identifier">be</span> <span class="identifier">equal</span><span class="special">.</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">23</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_collections_vectors_lex"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">&lt;</span> <span class="identifier">b</span> <span class="identifier">has</span> <span class="identifier">failed</span><span class="special">.</span>
<span class="identifier">Failure</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">2</span><span class="special">:</span> <span class="number">3</span> <span class="special">&gt;=</span> <span class="number">2.</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">24</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_collections_vectors_lex"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">==</span> <span class="identifier">b</span> <span class="identifier">has</span> <span class="identifier">failed</span><span class="special">.</span>
<span class="identifier">Mismatch</span> <span class="identifier">at</span> <span class="identifier">position</span> <span class="number">2</span><span class="special">:</span> <span class="number">3</span> <span class="special">!=</span> <span class="number">2.</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">25</span><span class="special">:</span> <span class="identifier">info</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">a</span> <span class="special">!=</span> <span class="identifier">b</span> <span class="identifier">has</span> <span class="identifier">passed</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">26</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_collections_vectors_lex"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">c</span> <span class="special">&lt;</span> <span class="identifier">d</span> <span class="identifier">has</span> <span class="identifier">failed</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">27</span><span class="special">:</span> <span class="identifier">error</span><span class="special">:</span> <span class="identifier">in</span> <span class="string">"test_collections_vectors_lex"</span><span class="special">:</span> <span class="identifier">check</span> <span class="identifier">c</span> <span class="special">==</span> <span class="identifier">d</span> <span class="identifier">has</span> <span class="identifier">failed</span>
<span class="identifier">test</span><span class="special">.</span><span class="identifier">cpp</span><span class="special">:</span><span class="number">17</span><span class="special">:</span> <span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="keyword">case</span> <span class="string">"test_collections_vectors_lex"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">155u</span><span class="identifier">s</span>
<span class="identifier">Leaving</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"boost_test_container_lex_default"</span><span class="special">;</span> <span class="identifier">testing</span> <span class="identifier">time</span><span class="special">:</span> <span class="number">177u</span><span class="identifier">s</span>

<span class="special">***</span> <span class="number">5</span> <span class="identifier">failures</span> <span class="identifier">are</span> <span class="identifier">detected</span> <span class="identifier">in</span> <span class="identifier">the</span> <span class="identifier">test</span> <span class="identifier">module</span> <span class="string">"boost_test_container_lex_default"</span>
</pre>
                </td></tr></tbody>
</table></div>
<h5>
<a name="boost_test.testing_tools.extended_comparison.collections.h12"></a>
          <span class="phrase"><a name="boost_test.testing_tools.extended_comparison.collections.requirements0"></a></span><a class="link" href="collections.html#boost_test.testing_tools.extended_comparison.collections.requirements0">Requirements</a>
        </h5>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
              the containers should meet the <a class="link" href="collections.html#what_is_a_collection">sequence</a>
              definition,
            </li>
<li class="listitem">
              the containers should be of the exact same type
            </li>
<li class="listitem">
              <code class="computeroutput"><span class="identifier">op</span></code> should be one of
              the comparison operator <code class="computeroutput"><span class="special">==</span></code>,
              <code class="computeroutput"><span class="special">!=</span></code>, <code class="computeroutput"><span class="special">&lt;</span></code>,
              <code class="computeroutput"><span class="special">&lt;=</span></code>, <code class="computeroutput"><span class="special">&gt;</span></code>,
              <code class="computeroutput"><span class="special">&gt;=</span></code>
            </li>
</ul></div>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
            Note that the operation <code class="computeroutput"><span class="special">!=</span></code>
            is in this case not an element-wise comparison,
          </p></td></tr>
</table></div>
<a name="what_is_a_collection"></a><h4>
<a name="boost_test.testing_tools.extended_comparison.collections.h13"></a>
          <span class="phrase"><a name="boost_test.testing_tools.extended_comparison.collections.what_is_a_sequence"></a></span><a class="link" href="collections.html#boost_test.testing_tools.extended_comparison.collections.what_is_a_sequence">What
          is a sequence?</a>
        </h4>
<p>
          A <span class="emphasis"><em>sequence</em></span> is given by the iteration over a <span class="emphasis"><em>forward
          iterable</em></span> container. A forward iterable container is:
        </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
              either a C-array,
            </li>
<li class="listitem">
              or a <code class="computeroutput"><span class="keyword">class</span></code>/<code class="computeroutput"><span class="keyword">struct</span></code> that implements the member functions
              <code class="computeroutput"><span class="identifier">begin</span></code> and <code class="computeroutput"><span class="identifier">end</span></code>.
            </li>
</ul></div>
<p>
          For collection comparisons, both sequences are also required to be different
          than <code class="computeroutput"><span class="identifier">string</span></code> sequences.
          In that case, the sequences are dispatched to string <a class="link" href="strings.html" title="Strings and C-strings comparison">comparison
          instead</a>.
        </p>
<div class="warning"><table border="0" summary="Warning">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../../../../../../../doc/src/images/warning.png"></td>
<th align="left">Warning</th>
</tr>
<tr><td align="left" valign="top"><p>
            <code class="computeroutput"><span class="identifier">string</span></code> (or <code class="computeroutput"><span class="identifier">wstring</span></code>) meets the sequence concept
            by definition, but their handling with <a class="link" href="../../utf_reference/testing_tool_ref/assertion_boost_test_universal_macro.html" title="BOOST_TEST"><code class="computeroutput"><span class="identifier">BOOST_TEST</span></code></a> is done differently.
            See <a class="link" href="strings.html" title="Strings and C-strings comparison">Strings
            and C-strings comparison</a> for more details.
          </p></td></tr>
</table></div>
<div class="tip"><table border="0" summary="Tip">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../../doc/src/images/tip.png"></td>
<th align="left">Tip</th>
</tr>
<tr><td align="left" valign="top"><p>
            If the behavior of <a class="link" href="../../utf_reference/testing_tool_ref/assertion_boost_test_universal_macro.html" title="BOOST_TEST"><code class="computeroutput"><span class="identifier">BOOST_TEST</span></code></a> is not the one you
            expect, you can always use raw comparison. See <a class="link" href="../boost_test_universal_macro.html#boost_test_statement_limitations">this
            section</a> for details.
          </p></td></tr>
</table></div>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
            Since <a class="link" href="../../change_log.html#ref_CHANGE_LOG_3_6">Boost.Test 3.6</a> (Boost
            1.65) the requirements for the collection concepts have been relaxed
            to include C-arrays as well
          </p></td></tr>
</table></div>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../../doc/src/images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
            Since <a class="link" href="../../change_log.html#ref_CHANGE_LOG_3_7">Boost.Test 3.7</a> (Boost
            1.67) the definition of <code class="computeroutput"><span class="identifier">const_iterator</span></code>
            and <code class="computeroutput"><span class="identifier">value_type</span></code> in the
            collection type is not required anymore (for the compilers properly supporting
            <code class="computeroutput"><span class="keyword">decltype</span></code>).
          </p></td></tr>
</table></div>
<p>
          The detection of the types that meet these requirements containers is delegated
          to the class <code class="computeroutput"><a class="link" href="../../../boost/unit_test/is_forward_iterable.html" title="Struct template is_forward_iterable">boost::unit_test::is_forward_iterable</a></code>,
          which for C++11 detects the required member functions and fields. However
          for C++03, the types providing the sequences should be explicitly indicated
          to the <span class="emphasis"><em>Unit Test Framework</em></span> by a specialization of
          <code class="computeroutput"><a class="link" href="../../../boost/unit_test/is_forward_iterable.html" title="Struct template is_forward_iterable">boost::unit_test::is_forward_iterable</a></code>
          <a href="#ftn.boost_test.testing_tools.extended_comparison.collections.f4" class="footnote" name="boost_test.testing_tools.extended_comparison.collections.f4"><sup class="footnote">[14]</sup></a>.
        </p>
<div class="footnotes">
<br><hr style="width:100; text-align:left;margin-left: 0">
<div id="ftn.boost_test.testing_tools.extended_comparison.collections.f0" class="footnote"><p><a href="#boost_test.testing_tools.extended_comparison.collections.f0" class="para"><sup class="para">[10] </sup></a>
                this might not be the case for e.g. <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">unordered_map</span></code>,
                for which the buckets might be filled differently depending on the
                insertion order.
              </p></div>
<div id="ftn.boost_test.testing_tools.extended_comparison.collections.f1" class="footnote"><p><a href="#boost_test.testing_tools.extended_comparison.collections.f1" class="para"><sup class="para">[11] </sup></a>
                in this case <code class="computeroutput"><span class="identifier">v_a</span> <span class="special">&lt;</span> <span class="identifier">v_b</span></code>
                means that the point <code class="computeroutput"><span class="identifier">v_a</span></code>
                is inside the rectangle (origin, <code class="computeroutput"><span class="identifier">v_b</span></code>)
              </p></div>
<div id="ftn.boost_test.testing_tools.extended_comparison.collections.f2" class="footnote"><p><a href="#boost_test.testing_tools.extended_comparison.collections.f2" class="para"><sup class="para">[12] </sup></a>
                either defined by the container or by the user
              </p></div>
<div id="ftn.boost_test.testing_tools.extended_comparison.collections.f3" class="footnote"><p><a href="#boost_test.testing_tools.extended_comparison.collections.f3" class="para"><sup class="para">[13] </sup></a>
            the containers should yield the same sequences for a fixed set of elements
            they contain
          </p></div>
<div id="ftn.boost_test.testing_tools.extended_comparison.collections.f4" class="footnote"><p><a href="#boost_test.testing_tools.extended_comparison.collections.f4" class="para"><sup class="para">[14] </sup></a>
            Standard containers of the <code class="computeroutput"><span class="identifier">STL</span></code>
            are recognized as <span class="emphasis"><em>forward iterable</em></span> container.
          </p></div>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2001-2022 Boost.Test contributors<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="strings.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../extended_comparison.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="bitwise.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
